Notes for the Trace plugin

Nov. 2009
L. Konneker
version 0.1


This is a mix of notes for users and programmers.

About the Trace plugin:

It has these main uses:
Simplifying an image to reduced colors and smooth outlines, like a cartoon or a collage.
Creating paths in an image, on outlines or centerlines.

It requires the separate program called autotrace.  Autotrace is a command line program, available free on the web, with package name "autotrace".

It simplifies the user interface to autotrace.  You have more control over autotrace if you invoke it directly from the command line 
(but it has bewildering parameters.)

It works by converting the image to vectors (curves), then back to pixels (a bitmap) and possibly paths (the Gimp name for vectors.)

FAQ's

Q. Why are there checkerboards or gaps between colors?  A. What you see as checkerboard is an uncolored background seen through
 a transparent foreground.  (You can see it as snow by choosing "Layer>Alpha to Selection".)  In other words, it is gaps between foreground regions.   The gaps are a limitation of the plugin and the tracing algorithms it uses.  Outlines are closed paths around pixel regions of the same color.  As vectors, the paths around two adjacent colors may not overlap in a strict mathematical sense.  
When paths are rendered to pixels and filled, some pixels between paths might not be colored.

Q. Why would I want paths?  A. You can paint (stroke) them or make selections using them.  (But it might be easier to select by color.) 
 You may very well not need the paths, just the simplifications that go with converting to and fro.

Q. Why does it trace text fonts and line art so poorly?  A. The Trace plugin uses an engine (autotrace) that does poorly on fonts and line art.
  Inkscape uses a different engine (potrace) that does better on fonts (but only in B&W.) 

How the Trace plugin works:

Saves the current image in a temporary png file.
Invokes autotrace on that file to create a temporary SVG file.
Imports the temporary svg file into a new image.
Deletes the temporary png file.

About Autotrace

Quoting the authors: AutoTrace is a program for converting bitmaps to vector graphics. The aim of the AutoTrace project is the development of a freely-available application similar 
to CorelTrace or Adobe Streamline. In some aspects it is already better. Originally created as a plugin for the GIMP, AutoTrace is now a standalone program.
Home Page: http://autotrace.sourceforge.net/

Autotrace, in order:
1) despeckles, removing small features.
2) quantizes to a reduced color range.
3) vectorizes, using a "watershed" algorithm, tracing either outlines divides between colors (watersheds) or centerlines (rivers in watersheds).

The vectorizing step:
1) detects corners or cusps
2) fits curves (splines or Bezier curves) between the corners

The parameters of Autotrace affect one or more of these steps.  Autotrace documents aren't clear which steps the parameters affect.

Bitmaps, vectors, Gimp, and Inkscape

Gimp mainly uses bitmaps and Inkscape mainly uses vectors, but both have limited support for the other format.
Gimp will import vectors and Inkscape will import bitmaps.  Inkscape will trace bitmaps to create vectors (but it does it in black and white.)

The Trace plugin for Gimp can be similar to: 
1) saving a bitmap image from Gimp
2) opening the bitmap image in Inkscape, tracing, and saving B&W SVG, 
3) reopening the B&W SVG image in Gimp,
4) restoring colors to the image

(But Inkscape uses a different tracing engine, called potrace.)

About SVG and bitmap images for the Web

For Web images, you might want SVG files because they scale with no loss of clarity or resolution.  
But not all web browsers now support scaling SVG images.  Many web browsers support limited scaling of bitmap images.
You can find the SVG files created by the Trace plugin in the Gimp temporary directory.
The SVG images created by the Trace plugin might not be smaller than comparable bitmap images.
In the future, some browsers might support smarter scaling of bitmap images, for example, using Liquid Rescale.

About competing tracing programs:

Potrace and autotrace are free software competitors. Autotrace does colors, potrace only black and white.
Autotrace will trace centerlines, potrace won't.  There is some evidence that potrace does a better job of tracing fonts.

CorelTrace and Adobe Streamline are commercial competitors.

About GUI front-ends for tracing programs:

Potracegui is a GUI (instead of command line) frontend (or wrapper) to autotrace and potrace (despite its name).
It uses KDE desktop environment on Linux (different from Gnome desktop.)

Frontline was a GUI frontend to autotrace.  It used the GTK (Gnome) desktop environment.
(Apparently it is not in most Linux distributions anymore.  The source is still available at SourceForge.  It would not easily compile for me.)

Delineate is a portable GUI front-end written in Java, distributed with autotrace.

Win32Trace is a GUI front-end to autotrace for MS Windows.

Inkscape has potrace built in.

About Gimp plugins for Autotrace:

Autotrace started as a plugin for Gimp, but is not any more.

Frontline had a plugin for Gimp, but apparently not any longer.

I couldn't find any other tracing plugin for Gimp.

About tracing in Gimp

Often tracing means "selecting the outline of".  The magic wand and the foreground select tool in Gimp help you do that.
Gimp can convert a path to a selection and vice versa.

Known limitations of the Trace plugin for Gimp

It does a poor job of tracing fonts, either outlines or centerlines.  Potrace might be a better engine for that.
 If you want to trace fonts, use Inkscape.

It leaves gaps between filled shapes (where the background shows through.)  A post processing step could fill in those gaps with the nearest color.
Or the tracing algorithm might generate splines that overlap so that there are no gaps.  

For now, the Trace plugin aborts without creating an image if autotrace generates a large SVG file size ( greater than 600 kilobytes)
and you have chosen "Create Paths: Many, Individual."  In this case, the Trace plugin presents a message "Trace plugin error:
SVG file has too many individual paths to import."  (If the plugin did not abort, the plugin (and Gimp) would lock up as it imports the SVG file.
Gimp can render the vectors quickly, but takes an inordinate amount of time to read them into Gimp paths.)


More notes:

The Trace plugin will trace down to one color for centerlines.  Then, the rest of the image is transparent.
(It makes no sense to trace down to one color for outlines, since it reduces the image to one color.)

The new, traced image size and resolution is the same as the original.

The new, traced image name has an .svg suffix.  To save the new, traced image, you must choose a different suffix
(file format) since Gimp won't save SVG.  However, whether or not you save the new image, the SVG format file created by autotrace
will remain in the Gimp temporary directory (so you can use it.)

Installation:

Install in the normal way for Gimp plugins on your platform.  Install the autotrace program normally
(to satisfy the requirement that the Trace plugin, or any other invocation from a shell, will find the executable file in the shell's search path.)


2019
MareroQ
version 0.2  autotrace does not support png files, add Usage


Usage: autotrace.exe [options] <input_name>.

Options:<input_name> should be a supported image.
  You can use `--' or `-' to start an option.
  You can use any unambiguous abbreviation for an option name.
  You can separate option names and values with `=' or ` '.
background-color <hexadecimal>: the color of the background that
  should be ignored, for example FFFFFF;
  default is no background color.
centerline: trace a character's centerline, rather than its outline.
color-count <unsigned>: number of colors a color bitmap is reduced to,
  it does not work on gray scale, allowed are 1..256;
  default is 0, that means not color reduction is done.
corner-always-threshold <angle-in-degrees>: if the angle at a pixel is
  less than this, it is considered a corner, even if it is within
  `corner-surround' pixels of another corner; default is 60.
corner-surround <unsigned>: number of pixels on either side of a
  point to consider when determining if that point is a corner;
  default is 4.
corner-threshold <angle-in-degrees>: if a pixel, its predecessor(s),
  and its successor(s) meet at an angle smaller than this, it's a
  corner; default is 100.
despeckle-level <unsigned>: 0..20; default is no despeckling.
despeckle-tightness <real>: 0.0..8.0; default is 2.0.
dpi <unsigned>: The dots per inch value in the input image, affects scaling
  of mif output image
error-threshold <real>: subdivide fitted curves that are off by
  more pixels than this; default is 2.0.
filter-iterations <unsigned>: smooth the curve this many times
  before fitting; default is 4.
  
input-format:  TGA, PBM, PNM, PGM, PPM or BMP.

help: print this message.
line-reversion-threshold <real>: if a spline is closer to a straight
  line than this, weighted by the square of the curve length, keep it a
  straight line even if it is a list with curves; default is .01.
line-threshold <real>: if the spline is not more than this far away
  from the straight line defined by its endpoints,
  then output a straight line; default is 1.
list-output-formats: print a list of support output formats to stderr.
list-input-formats:  print a list of support input formats to stderr.
log: write detailed progress reports to <input_name>.log.
output-file <filename>: write to <filename>
output-format <format>: use format <format> for the output file
output-format <format>: use format <format> for the output file
  eps, ai, p2e, sk, svg, fig, swf, emf, mif, er, dxf, epd, pdf, cgm or dr2d
  can be used.
preserve-width: whether to preserve line width prior to thinning.\n\
remove-adjacent-corners: remove corners that are adjacent.
tangent-surround <unsigned>: number of points on either side of a
  point to consider when computing the tangent at that point; default is 3.
report-progress: report tracing status in real time.
debug-arch: print the type of cpu.
debug-bitmap: dump loaded bitmap to <input_name>.bitmap.
version: print the version number of this program.
width-weight-factor: weight factor for fitting the line width.